	##############################################
   ### MySource ------------------------------###
  ##- Installation Instructions --------------##
 #-- Copyright Squiz.net ---------------------#
##############################################

Herein are the instructions from installing and setting up MySource
on your system.

It is assumed your system satisfies all the MySource requirements.
If not, please ensure that it does before commencing installation.

===================
System Requirements
===================

MySource is currently only supported under Linux running the Apache
web server.

Hardware Requirements:

  We are still determining the hardware requirements of MySource. We
  doubt however these will exceed the requirements of a standard, but
  serious web server serving dynamic content.

Software Requirements:

  * GNU/Linux 2.0+
  * Apache 1.3
  * PHP 4.3.0
	* PNG Support (and required libraries)
	* GIF Support (and required libraries) (if your designs use them)
	* MySQL Support
  * MySQL 3.23


MySQL Requirements
------------------
-- http://www.mysql.com/downloads/
   Please Choose a mirror close to you.
-- It is downloadable either as an RPM or if you prefer, source code.
   Make sure you install the "devel" RPM if you choose to install
   with RPM's.

-- Version greater than 3.23.35.
   This is where it was developed, and has been extensively tested.
   Earlier versions are not guaranteed to work.


PHP Requirements
----------------
-- Downloadable only as source, http://www.php.net/downloads.php
   Choose a mirror close to you.
-- It is only downloadable as source code.

-- Version greater than 4.2.0
   This has some commands that previous versions of PHP didn't, so we
   need to make sure they are available for use.

   In summary, the minimum configure command for PHP has to have these
   options enabled:

   --with-gd
   --with-png-dir
   --with-zlib-dir
   --with-jpeg-dir
   --with-mysql

If you already have any other configuration options for PHP, add the
above options to them.

Recompile PHP, and test these options are available.

-- In the php.ini file, the "Short Tags" have to be enabled, with the
   line "short_open_tag = On"
   (This doesn't need compiling in, Apache just needs restarting to
   read in the INI file again).

Known Working PHP configure command
-----------------------------------
A php configure command known to work with MySource is as follows.

./configure \
--with-apxs=/usr/local/apache/bin/apxs \
--with-config-file-path=/etc \
--enable-versioning \
--enable-inline-optimization \
--enable-memory-limit \
--with-mysql=shared,/usr \
--with-gd=shared,/usr \
--enable-gd-native-ttf \
--with-ttf=/usr \
--with-xml \
--enable-wddx \
--with-zlib-dir=/usr \
--enable-mbstring \
--without-pear

Please note that this command does include options not specific to MySource and it is HIGHLY recommended that you install and review your php.ini file after installation of php.

This configure command relies on mod_so being built into Apache which allows you to load the php module without having to recompile apache. It has been successfully run on all Redhat Linux distributions between 6.2 and 7.3 inclusive using a compiled from source version of Apache 1.3.

To check if mod_so has been built into Apache run the command httpd -l and check to confirm that mod_so.c is in the output from running the command.



About Libraries Needed
----------------------

-- JPEG Libraries
   The JPEG libraries allow you to create / modify images "on the fly".
   MySource requires version 6b-10 or greater.

   They are available from:
   RedHat 6.2 - ftp://ftp.redhat.com/pub/redhat/redhat-6.2-en/os/i386/RedHat/RPMS/libjpeg-6b-10.i386.rpm
				ftp://ftp.redhat.com/pub/redhat/redhat-6.2-en/os/i386/RedHat/RPMS/libjpeg-devel-6b-10.i386.rpm
   RedHat 7.1 - ftp://ftp.redhat.com/pub/redhat/redhat-7.1-en/os/i386/RedHat/RPMS/libjpeg-6b-10.i386.rpm
				ftp://ftp.redhat.com/pub/redhat/redhat-7.1-en/os/i386/RedHat/RPMS/libjpeg-devel-6b-10.i386.rpm
   The RedHat 7.1 version is compatible with RedHat 7.0.

   If you prefer, the source code is available from
   ftp://ftp.uu.net/graphics/jpeg/

-- GD With GIF Library
   The GD libraries allow you to create / modify images "on the fly".
   This library also allows you to create / modify PNG images.
   The RPM is available from http://rpms.arvin.dk/gd-with_gif/ .
   A Source RPM is also available from this site. If you install from
   RPM's, remember to install the "devel" RPM, this is the one PHP
   needs.

   If you prefer, the source code is available from
   http://www.boutell.com/gd/

   Note : When you run the configure command for PHP, the default
   install location of the RPM is /usr/gd-with_gif, PHP doesn't look
   there by default so you have to tell it the path.
   Whatever location you use for --with-gd, you need to use the same
   location for --with-png when you configure PHP.

   Note: If your don't use GIFs in your site designs, you do not need
   GD With GIF.

-- ZLib
   The ZLib libraries allow compression of files, this is used by PNG
   so we need to add it into PHP.
   The source & RPM are available from http://www.gzip.org/zlib/

   Note: The RPM by default installs into /usr, so add this to the
   PHP configure command.


============
Installation
============


Unzip and untar the MySource tarball (if you're reading this you've
probably already done that :):

$ gunzip -c mysource-x.x.tgz | tar xf -
$ cd mysource
$ ./configure

If the configure command returns an error message about a bad interpreter,
the script isn't executable. To fix this, simply:

$ chmod +x ./configure

and try running configure again.

The configure script will prompt you for information as it:

	* Generates the inital configuration options (which can be altered
	  later)
	* Creates the MySQL database(s) and their tables.
	* Generates some example Apache configuration lines, which you
	  can paste into your httpd.conf file if you wish.

Any included MySource Xtras will be automatically installed during
this procedure as well.

The other alternative is to copy the "install.php" file into a web 
server accessable directory, and look at it through your browser.
Fill in the details, hit "Install", and you will be presented with
the details to copy into your httpd.conf file.

====================
Apache Configuration
====================

For now MySource is only supported running on the Apache web server.

There are two different ways to run the MySource web system - that is
whether or not to use "Virtual Paths". Virtual paths simulate a
directory structure on the web server, based on your MySource page
hierarchy. This way you can have URLs to your resources such as:

	http://mysource.squiz.net/downloads/mysource_0.9.1.tgz

Without Virtual Paths turned on (in the MySource configuration) you
need to instead use the URL:

	http://mysource.squiz.net/?f=63

This alternative is less friendly to site visitors - not to mention
search engine spiders and picky browsers!

Unfortunately to enable Virtual Paths you need access to Apache's
configuration file, which some MySource users will not have. This
is why turning Virtual Paths on is optional.

The key to running MySource using Virtual Paths are these five lines
in your Apache configuration:

	AliasMatch "^/(.*/)?__lib(.*)$" "MYSOURCE_PATH/web/__lib$2"
	AliasMatch "^/(.*/)?__squizlib(.*)$" "MYSOURCE_PATH/squizlib$2"
	AliasMatch "^/(.*/)?__data(.*)$" "MYSOURCE_PATH/data/unrestricted$2"
	AliasMatch "^/(.*/)?_edit(.*)$" "MYSOURCE_PATH/web/edit$2"
	AliasMatch "^/.*$" "MYSOURCE_PATH/web/index.php"

Where MYSOURCE_PATH is the path to the directory where you 
extracted MySource. The configure script should generate custom
lines for you (check for a file called Apache.conf after you run
configure).

The first line ensures that you can always access the MySource
backend by attaching "_edit" to any MySource URL. If you wish
to have a different suffix for your backend, simply change the
"_edit" in that line to "_admin" or "__BACKEND__" or whatever takes
your fancy. You do not need to include underscores (_'s) but it is
a nice way to distuguish between the backend and just another 
sub-page. For example, to edit the file mentioned above:

http://mysource.squiz.net/downloads/mysource_0.9.1.tgz/_edit

The first AliasMatch line overrides the second one which says
"every request made at this domain should be handled by the MySource
frontend controller". E.g.:

http://mysource.squiz.net/
http://mysource.squiz.net/downloads
http://mysource.squiz.net/a/really/long/path/that/actually/doesnt/go/anywhere

These will all be handled by MySource. If MySource can't find a
matching resource, it will redirect the user to the closest match.

If you only want to use MySource at a sub-directory of a domain, e.g.:

http://mysource.squiz.net/steve/mysource_test/

simply alter the lines as such:

	AliasMatch "^/steve/mysource_test(/.*)?/__lib(.*)$" "MYSOURCE_PATH/web/__lib$2"
	AliasMatch "^/steve/mysource_test(/.*)?/__squizlib(.*)$" "MYSOURCE_PATH/squizlib$2"
	AliasMatch "^/steve/mysource_test(/.*)?/__data(.*)$" "MYSOURCE_PATH/data/unrestricted$2"
	AliasMatch "^/steve/mysource_test(/.*)?/_edit(.*)$" "MYSOURCE_PATH/web/edit$2"
	AliasMatch "^/steve/mysource_test(/.*)?$" "MYSOURCE_PATH/web/index.php"


If you don't have access to the Apache configuration, then you will need to set up some symlinks instead.
This means you can't have a url like http://mysource.squiz.net/steve/mysource_test/ , instead it will be http://mysource.squiz.net/?p=19 .

Set up the symlinks (relative to the MySource root) 'web/__squizlib' 
pointing to 'squizlib' and '__data' pointing to 'data/unrestricted'. 
E.g.:

[/home/mysource]$ cd web
[/home/mysource/web]$ ln -s ../squizlib __squizlib
[/home/mysource/web]$ ln -s ../data/unrestricted __data

If you keep the default "_edit" suffix for editing, you will need one more symlink.
If you prefer a different suffix, adjust accordingly.

[/home/mysource/web]$ ln -s ./edit ./_edit


How ever you set up your Apache configuration or if you are using symlinks, remember to configure
MySource itself accordingly. Under the "Config" tab in the MySource
backend, specify whether or not you are using Virtual Paths, and if
so, specify which suffix you are using (default is "_edit").


====================
Tomcat Configuration
====================

A recent feature added to MySource is a Java-based bulk file
uploader called 'jupload'. This system consists of a
browser-side Java applet and a server-side Java servlet. We
have successfully tested jupload on a system running Apache
and Tomcat. jupload can be found in the "squizlib/jupload"
directory. If you have tomcat running on your system you can
enable jupload by symlinking (or copying) this directory into
your Tomcat "webapps" directory. You can then specify the
appropriate URL to the directory in the MySource Configuration
screen. E.g. "http://www.example.com/jupload/"



For more information visit our website.

Best of luck,

The MySource Team
http://mysource.squiz.net/
